home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / Pasc / TN.PASC.012 < prev    next >
Encoding:
Text File  |  1988-12-21  |  13.6 KB  |  308 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Pascal
  8. #12:    Disk Formatter Routine
  9.  
  10. Revised by:    Cheryl Ewy & Dan Strnad                          November 1988
  11. Revised by:    Cheryl Ewy                                           June 1985
  12.  
  13. This Technical Note documents the Apple II Pascal 1.3 Disk Formatter routine.
  14. _____________________________________________________________________________
  15.  
  16.  
  17. Introduction
  18.  
  19. Integrating the Pascal Disk Formatter utility into your application program 
  20. will free the user from having to format Pascal disks prior to running your 
  21. program.  Error codes that specify any problems encountered during the 
  22. formatting process are returned.  The disk contains the following files:
  23.  
  24. FORMATTER.TEXT is a sample Pascal host program that illustrates the use of the 
  25. formatter routine.
  26.  
  27. FORMDISK.TEXT is an assembly language function that is linked to your Pascal 
  28. host program.  It contains the code to format disks in ProDOS blocked devices 
  29. and calls the ASMFORMAT function to format disks in Disk II drives.
  30.  
  31. ASMFORMAT.TEXT is the Disk II formatter, an assembly language procedure that 
  32. must be specially handled (see below).
  33.  
  34. BOOTTRACKS.DATA is a data file that is used to create the formatter data file.  
  35. It contains boot blocks for both Disk II drives and ProDOS blocked devices and 
  36. a blank disk directory.
  37.  
  38. MAKEFMT.TEXT, MAKEFMT.CODE are a Pascal program that will create the required 
  39. formatter data file.
  40.  
  41. FORMATTER.DATA is a complete formatter data file (identical to that supplied 
  42. with the Apple II Pascal 1.3 Development System).
  43.  
  44. FORMATTER.CODE is the formatter program supplied with the Apple II Pascal 1.3 
  45. Development System.
  46.  
  47. All programs are supplied in source (and where appropriate, as code files) so 
  48. that you may modify them for your own particular purposes.
  49.  
  50.  
  51. ASMFORMAT - The Disk II Formatter Routine
  52.  
  53. The file ASMFORMAT.TEXT contains a proprietary subroutine that performs the 
  54. actual formatting of Disk II disks.  It is written in 6502 assembly language 
  55. suitable for assembly by the Apple II or Apple /// Pascal Assembler.  This 
  56. code requires special handling by the host program to ensure a reliable 
  57. format.  It contains critical timing code, and because of this, it must be 
  58. located on a page boundary in memory (a location of the form xx00, e.g., 3D00, 
  59. 2000, etc.).  To do this, it must be assembled ABSOLUTE and you must use ORG 
  60. to place it on particular page boundary.  It comes supplied at location 3D00, 
  61. which is the location used by the formatter routine supplied with the Apple II 
  62. Pascal 1.3 Development System (FORMATTER.CODE).  If you need to move it to 
  63. another particular location you must change the .ORG statement in the file to 
  64. the new address.  The formatter will not work reliably if it is not on a page 
  65. boundary.  The code itself is 1082 bytes in length.
  66.  
  67. Because of the special nature of this code, it must be loaded by the Pascal 
  68. host program at the chosen location.  The following sample code illustrates 
  69. how this is done:
  70.  
  71.     TYPE MEMARRAY = PACKED ARRAY [0..1535] OF 0..255;
  72.  
  73.         MEMPTR = RECORD CASE BOOLEAN OF
  74.                 TRUE:  (ADDR: INTEGER);
  75.                 FALSE: (MEM: ^MEMARRAY);
  76.             END;
  77.  
  78.     VAR  LOADPTR: MEMPTR;     {this is the pointer to the absolute memory 
  79.                               location where the Disk II formatter routine 
  80.                               will be loaded.}
  81.  
  82.  
  83.         {the following code will load the Disk II formatter routine
  84.         from the formatter data file into memory at a fixed location}
  85.  
  86.         RESET(DATAFILE, '%FORMATTER.DATA');
  87.  
  88.         LOADPTR.ADDR := 15616;    {this value is the absolute memory location
  89.                                   where the code is to be loaded.  In this
  90.                                   example, 15316 is the decimal equivalent of
  91.                                   the memory address 3D00.}
  92.  
  93.         BLOCKSREAD := BLOCKREAD(DATAFILE, LOADPTR.MEM^, 3);
  94. {the above line will load three blocks (the Disk II formatter code) from the data file into 
  95. the memory space specified in LOADPTR} 
  96.  
  97. The Disk II formatter routine assumes that the A register has been setup with 
  98. the slot number and drive number of the disk which is to be formatted.  
  99. FORMDISK sets up this information before doing a JSR to the Disk II formatter 
  100. routine.  The contents of the A register are defined as follows:
  101.  
  102.     Bit 7       Drive number.  0=Drive 1, 1=Drive 2
  103.     Bits 6-4    Slot number.  100=4, 101=5, 110=6.  No other slots are
  104.                               supported.
  105.     Bits 3-0    Reserved; must be set to zero.
  106.  
  107. After the Disk II formatter routine is called, it returns an error code in the 
  108. A register.  FORMDISK then returns this error code to the host program.  The 
  109. error codes are listed in the following section.
  110.  
  111.  
  112. FORMDISK - The Main Formatter Routine
  113.  
  114. The file FORMDISK.TEXT is an assembly language function that is assembled and 
  115. linked to your Pascal host program.  This function determines whether the 
  116. drive containing the disk to be formatted is a Disk II drive or a ProDOS 
  117. blocked device.  If it is a Disk II drive, FORMDISK invokes the Disk II 
  118. formatter routine with the required parameters as described in the previous 
  119. section.  If the drive is a ProDOS blocked device, FORMDISK sets up the proper 
  120. parameters and executes a format call to the device.  FORMDISK will return an 
  121. error code back to the Pascal host after the formatting is complete.  The call 
  122. to this function is shown below:
  123.  
  124.      VAR  ERRCODE: INTEGER;            {the error code returned}
  125.           VOLNUM:  INTEGER;            {the volume (unit) number of the disk}
  126.      ERRCODE := FORMDISK(VOLNUM);      {the function call}
  127.  
  128. There are six possible error codes returned by FORMDISK.  They indicate 
  129. problems that may have occurred during the formatting process.  They are as 
  130. follows:
  131.  
  132. Error code  Error                        Possible causes
  133. _____________________________________________________________________________
  134. 00          No Error                     Formatting successfully completed
  135.  
  136. 39          Unable to format the disk    No disk in drive; drive door not 
  137.                                          closed; bad media
  138.  
  139. 43          Disk is write-protected      Disk is write-protected; disk is
  140.                                          pushed halfway into drive,
  141.                                          activating the write-protect switch
  142.  
  143. 47          No disk in drive             The disk drive is empty.  This error
  144.                                          is only reported for ProDOS block
  145.                                          devices.  If a Disk II drive is empty,
  146.                                          error #39 is returned.
  147.  
  148. 51          Drive speed is too slow      The drive motor speed requires 
  149.                                          adjustment, it is too slow.  This
  150.                                          erroris only reported for Disk IIs.
  151.  
  152. 52          Drive speed is too fast      The drive motor speed requires 
  153.                                          adjustment, it is too fast.  This
  154.                                          error is only reported for Disk IIs.
  155.  
  156. To use the FORMDISK function requires that you modify one .EQU statement in  
  157. the source file (FORMDISK.TEXT) to specify the location of the Disk II 
  158. formatter routine in memory.  Currently, the statement reads as follows:
  159.  
  160.     DO_FORMAT   .EQU   3D00   ;memory address of the Disk II formatter routine
  161.  
  162. If you decide to relocate the Disk II formatter routine, simply change this 
  163. value to reflect the new memory address, then reassemble FORMDISK.  The 
  164. FORMDISK function does a JSR to this value to invoke the Disk II formatter 
  165. routine.
  166.  
  167. Note:    The value used in the .ORG in ASMFORMAT and the .EQU in 
  168. FORMDISK must match.
  169.  
  170.  
  171. Making a Formatter Data File
  172.  
  173. To use the formatter requires a data file that contains three pieces:
  174.  
  175. 1.    The Disk II formatter routine code, to be loaded into memory.
  176. 2.    The boot code that is written to blocks 0 and 1 of the formatted 
  177.       disk.
  178. 3.    A blank UCSD Pascal directory that is written to block 2 of the 
  179.       formatted disk. 
  180.  
  181. The formatter disk comes with the second and third parts in the file 
  182. BOOTTRACKS.DATA.  This four-block file contains the boot blocks for Disk II 
  183. drives and ProDOS blocked devices and the blank directory.  Once the Disk II 
  184. formatter routine has been assembled (to ASMFORMAT.CODE) it must be 
  185. concatenated to the BOOTTRACKS.DATA file to make the formatter data file.  The 
  186. Disk II formatter routine code occupies the first 3 blocks of the formatter 
  187. data file, which is then followed by the contents of the BOOTTRACKS.DATA file.  
  188. Because the assembler puts special informational content blocks into a code 
  189. file, a special program is required to copy only the blocks containing the 
  190. code of the Disk II formatter routine.  This is the program MAKEFMT.CODE.  
  191. This program copies blocks 1, 2, and 3 of ASMFORMAT.CODE to blocks 0, 1, and 2 
  192. of the file FORMATTER.DATA.  It then copies blocks 0, 1, 2, and 3 of the file 
  193. BOOTTRACKS.DATA to blocks 3, 4, 5, and 6 of the file FORMATTER.DATA.  This 
  194. makes the required formatter data file (7 blocks in size) that will be used by 
  195. the Pascal host program.  MAKEFMT requires that the files ASMFORMAT.CODE and 
  196. BOOTTRACKS.DATA be on the prefix volume.  Set the Pascal prefix to this volume 
  197. and X(ecute MAKEFMT.  It will create the file FORMATTER.DATA on the same 
  198. volume.  The source for this program is included so that you may modify it as 
  199. needed.
  200.  
  201.  
  202. The Pascal Host Program
  203.  
  204. It is up to you to write the Pascal host program.  On the disk is a sample 
  205. program (the Apple II Pascal 1.3 Formatter) that you may study.  It 
  206. illustrates the above techniques.  The primary functions of the Pascal host 
  207. are to:
  208.  
  209. 1.    Open the FORMATTER.DATA file.
  210. 2.    Read blocks 0 - 2 into a memory location that is on a page 
  211.       boundary.
  212. 3.    Read blocks 3 - 6 into a 2,048 byte buffer.
  213. 4.    Call the assembly language function FORMDISK with the volume 
  214.       number of the drive containing the disk to be formatted.
  215. 5.    Examine the error code returned.  If there is an error then report 
  216.       it to the user, otherwise continue.
  217. 6.    Use UNITSTATUS to determine whether the drive is a Disk II or a 
  218.       ProDOS blocked device and how many blocks are on the disk.
  219. 7.    Use the number of blocks returned by UNITSTATUS to update the 
  220.       maximum block number information in the blank directory.
  221. 8.    If the drive is a Disk II, use UNITWRITE to write blocks 0 - 2 
  222.       from the buffer to blocks 0 - 2 on the newly formatted disk.
  223. 9.    If the drive is a ProDOS blocked device, use UNITWRITE to write 
  224.       block 3 from the buffer to block 0 on the newly formatted disk, 
  225.       then use it again to write block 2 from the buffer to block 2 on 
  226.       the disk.
  227.  
  228. The following code is an example of how to read in the blocks from the 
  229. FORMATTER.DATA file, determine the drive type, update the directory, and write 
  230. the boot blocks and directory to the newly formatted disk:
  231.  
  232.     TYPE BYTARRAY = PACKED ARRAY [0..1] OF 0..255;
  233.  
  234.     VAR  BUFFER: PACKED ARRAY [0..2048] OF 0..255;
  235.  
  236.     NUMBLOCKS : INTEGER; 
  237.  
  238.     TRIX : RECORD CASE BOOLEAN OF
  239.                 TRUE  : (INT : INTEGER);
  240.                 FALSE : (BYT : BYTARRAY);
  241.             END; 
  242.  
  243.     {read in the boot blocks and directory}
  244.     NUMBLOCKS := BLOCKREAD (DATAFILE, BUFFER, 4, 3);
  245.  
  246.     {determine type of disk drive and number of blocks on the disk}
  247.     UNITSTATUS (VOLNUM, NUMBLOCKS, 1); 
  248.  
  249.     {update maximum number of blocks in blank directory}
  250.     TRIX.INT := NUMBLOCKS; 
  251.     BUFFER[1038] := TRIX.BYT[0];
  252.     BUFFER[1039] := TRIX.BYT[1];
  253.  
  254.     {write out the boot blocks and directory to a Disk II disk}
  255.     UNITWRITE (VOLNUM, BUFFER, 1536, 0);
  256.  
  257.     {write out the boot block and directory to a ProDOS blocked device disk}
  258.     UNITWRITE (VOLNUM, BUFFER[1536], 512, 0);
  259.     UNITWRITE (VOLNUM, BUFFER[1024], 512, 2);
  260.  
  261. A dynamic variable can also be used as the buffer so that your program can 
  262. reclaim the buffer space for its own use after the formatting is completed:
  263.  
  264.     TYPE BUFFER = PACKED ARRAY [0..2048] OF 0..255;
  265.  
  266.     VAR BUFPTR : ^BUFFER;
  267.     OLDPTR : ^INTEGER;
  268.  
  269.      {mark the beginning of usable space}
  270.     MARK (OLDPTR);
  271.      {allocate space for the buffer}
  272.     NEW (BUFPTR);
  273.      {read in the boot blocks and directory}
  274.     NUMBLOCKS := BLOCKREAD (DATAFILE, BUFPTR^, 4, 3);
  275.     {write out the boot blocks and directory to a Disk II disk}
  276.     UNITWRITE (VOLNUM, BUFPTR^, 1536, 0);
  277.     {release the space used by the buffer}
  278.     RELEASE (OLDPTR);
  279.  
  280.  
  281. In Review
  282.  
  283. The following is a step-by-step review of how to use the formatting routine.
  284.  
  285.  1.    Determine where in memory you wish to load the Disk II formatter 
  286.        routine.  Remember it must be on a page boundary.
  287.  2.    Edit the file ASMFORMAT.TEXT, and change the value in the .ORG 
  288.        statement to be the memory address chosen.
  289.  3.    Assemble ASMFORMAT.TEXT to ASMFORMAT.CODE.
  290.  4.    X(ecute MAKEFMT to make the required FORMATTER.DATA file.
  291.  5.    Edit the file FORMDISK.TEXT and change the line
  292.  
  293.            DO_FORMAT   .EQU   3D00
  294.  
  295.        to reflect the new memory location (same value as in the .ORG 
  296.        statement  above).
  297.  6.    Assemble FORMDISK.TEXT to FORMDISK.CODE.
  298.  7.    Write the Pascal host program using the above techniques for 
  299.        loading the Disk II formatter routine, calling the FORMDISK 
  300.        function, updating the blank directory, and writing the boot 
  301.        blocks and directory.  Remember error reporting.
  302.  8.    Compile the Pascal host.
  303.  9.    Link the Pascal host to the file FORMDISK.CODE, thus linking the 
  304.        FORMDISK function into your program.
  305. 10.    With the linked Pascal host program and the FORMATTER.DATA file 
  306.        you can now format disks.
  307.  
  308.